Packet Builder Functions

The following functions may be called by media packetizers during execution of an RTPMPSetSampleData or RTPMPIdle routine. Use them to tell a packet builder component to begin a packet group, to begin a packet, to insert data into a packet, to end a packet, and to end a packet group. These functions are only called by media packetizer components.

RTPPBBeginPacketGroup

Tell a packet builder to create a new packet group. The function returns a data reference which will be used when creating new packets or inserting data into packets.



 
ComponentResult RTPPBBeginPacketGroup (

                     RTPPacketBuilder rtpb,

                     SInt32 inFlags,

                     UInt32 inTimeStamp,

                     RTPPacketGroupRef *outPacketGroup);

rtpb: The component instance of the packet builder component
inFlags: A signed 32-bit integer containing any flags you are passing. There are currently no defined flags.
inTimeStamp: A unsigned 32-bit integer containing the time stamp for this packet group
outPacketGroup: On return, contains a pointer to a reference to the packet group. Use this data reference when creating a new packet or inserting data into a packet that belongs to this group

DISCUSSION

A media packetizer creates a packet group using this function. The data reference returned by this function is then used to create a series of packets that belong to this group. The data reference is also required when inserting data into packets. When the packet group is complete, call RTPPBEndPacketGroup .

RTPPBBeginPacket

Tell a packet builder to create a new packet . The function returns a data reference which will be used when creating inserting data into the packet.



 
ComponentResult RTPPBBeginPacket (

                     RTPPacketBuilder rtpb,

                     SInt32 inFlags,

                     RTPPacketGroupRef inPacketGroup,

                     UInt32 inPacketMediaDataLength,             RTPPacketRef *outPacket);

rtpb: The component instance of the packet builder component
inFlags: A signed 32-bit integer containing any flags you are passing. There are currently no defined flags.
inPacketGroup: The packet group containing the new packet. This is normally a reference returned by RTPPBBeginPacketGroup .
inPacketMediaDataLength: An unsigned 32-bit integer specifying the maximum length of data that will be inserted into this packet. This includes the data for all subsequent RTPPBAddPacketLiteralData , RTPPBAddPacketSampleData , and RTPPBAddPacketRepeatedData calls until the packet is closed. inPacketMediaDataLength may be larger, but must not be smaller, than the amount of data inserted in the packet.
outPacket: On return, contains a pointer to the packet. Use this reference to insert data into the packet.

DISCUSSION

The media packetizer uses this function to create each new packet, prior to inserting any literal, repeated, and/or sample data. A call to RTPPBBeginPacketGroup must be made prior to creating the first packet in a group. Data is inserted into the packet using RTPPBAddPacketLiteralData , RTPPBAddPacketRepeatedData , and/or RTPPBAddPacketSampleData . When the packet is complete, call RTPPBEndPacket .

RTPPBAddPacketLiteralData

Pass literal data directly to a packet builder component. For example, use this function to insert static header information into a packet prior to inserting media sample data. This function will return a data reference you can use to insert the same static information into later packets.



 
ComponentResult RTPPBAddPacketLiteralData (

                     RTPPacketBuilder rtpb,

                     SInt32 inFlags,

                     RTPPacketGroupRef inPacketGroup,

                     RTPPacketRef inPacket,

                     UInt8 *inData,

                     UInt32 inDataLength,

                     RTPPacketRepeatedDataRef *outDataRef);

rtpb: The component instance of the packet builder component
inFlags: A signed 32-bit integer containing any flags you are passing. There are currently no defined flags.
inPacketGroup: The packet group containing the packet into which the data will be placed. This is normally a reference returned by RTPPBBeginPacketGroup .
inPacket: The RTP packet into which the data will be placed. This is normally a reference returned by RTPPBBeginPacket .
inData: A pointer to the data you are passing
inDataLength: An unsigned 32-bit integer containing the length, in bytes, of the data you are passing
outDataRef: On return, contains a pointer to a data reference. Use this reference if you wish to later tell the packet builder to use this same data again, without having to literally pass the data again. Pass in nil if you do not need the packet builder to repeat the data. If you do not pass in nil , you must dispose of the data explicitly by calling RTPPBReleaseRepeatedData .

DISCUSSION

This function will return a reference which can be used to specify the same data repeatedly without having to pass in the data again. This is done by calling RTPPBAddPacketRepeatedData with the reference which was returned by RTPPBAddPacketLiteralData . When a reference is no longer needed, it should be disposed of by using the call RTPPBReleaseRepeatedData . To specify media data to be placed in a packet, a media packetizer should call RTPPBAddPacketSampleData .

RTPPBAddPacketSampleData

A media packetizer uses this function to command a packet builder component to insert media sample data into a packet. This typically follows static header information inserted by calling either RTPPBAddPacketLiteralData or RTPPBAddPacketRepeatedData . The media packetizer specifies the offset into the media and the length of the sample to insert.



 
ComponentResult RTPPBAddPacketSampleData (

                     RTPPacketBuilder rtpb,

                     SInt32 inFlags,

                     RTPPacketGroupRef inPacketGroup,

                     RTPPacketRef inPacket,

                     RTPMPSampleDataParams *inSampleDataParams,

                     UInt32 inSampleOffset,

                     UInt32 inSampleDataLength,

                     RTPPacketRepeatedDataRef *outDataRef);

rtpb: The component instance of the packet builder component
inFlags: A signed 32-bit integer containing any flags you are passing. There are currently no defined flags.
inPacketGroup: The packet group containing the packet into which the data will be placed. This is normally a reference returned by RTPPBBeginPacketGroup .
inPacket: The RTP packet into which the data will be placed. This is normally a reference returned by RTPPBBeginPacket .
inSampleDataParams: A pointer to a SampleDataParams structure for the sample data you are inserting.
inSampleOffset: A 32-bit unsigned integer containing the offset into the sample media, in bytes
inSampleDataLength: A 32-bit unsigned integer specifying the number of bytes of media sample data to insert into the packet
outDataRef: On return, contains a pointer to a data reference. Use this reference if you wish to later tell the packet builder to use this same sample data again, without having to literally pass the data again. Pass in nil if you do not need the packet builder to repeat the data. If you do not pass in nil , you must dispose of the data explicitly by calling RTPPBReleaseRepeatedData .

DISCUSSION

RTPPBAddPacketRepeatedData

Tell a packet builder component to insert previously-specified data into a packet. This is typically done to repeat static header information into a series of packets, or to insert previously-sent sample data into a redundant packet. The data is first specified by a call to RTPPBAddPacketLiteralData or RTPPBAddPacketSampleData , which inserts the data the first time and returns a data reference. Use the data reference with RTPPBAddPacketRepeatedData to send the data again.



 
ComponentResult RTPPBAddPacketRepeatedData (

                     RTPPacketBuilder rtpb,

                     SInt32 inFlags,

                     RTPPacketGroupRef inPacketGroup,

                     RTPPacketRef inPacket,

                     RTPPacketRepeatedDataRef inDataRef);

rtpb: The component instance of the packet builder component
inFlags: A signed 32-bit integer containing any flags you are passing. There are currently no defined flags.
inPacketGroup: The packet group containing the packet into which the data will be placed. This is normally a reference returned by RTPPBBeginPacketGroup .
inPacket: The RTP packet into which the data will be placed. This is normally a reference returned by RTPPBBeginPacket .
inDataRef: A reference to the data to repeat (this is normally a data reference returned from RTPPBAddPacketLiteralData or RTPPBAddPacketSampleData ).

DISCUSSION

Use this function to cause a packet builder component to repeatedly insert the same data into packets without having to pass the data each time. When you are done sending the repeated data, release the data structure by calling RTPPBReleaseRepeatedData .

RTPPBReleaseRepeatedData

Allow a packet builder to deallocate data that will no longer be used.



 
ComponentResult RTPPBReleaseRepeatedData (

                     RTPPacketBuilder rtpb,

                     RTPPacketRepeatedDataRef inDataRef);

rtpb: The component instance of the packet builder component
inDataRef: The data reference to the repeated data. This is normally a data reference returned by RTPPBAddPacketLiteralData or RTPPBAddPacketSampleData .

DISCUSSION

When a media packetizer passes data to a packet builder using RTPPBAddPacketLiteralData or RTPPBAddPacketSampleData , the packet builder can return a data reference. The media packetizer can use this data reference to insert the same data into other packets. The media packetizer must release this data when it is no longer needed.

You must release the data if you have allowed RTPPBAddPacketLiteralData or RTPPBAddPacketSampleData to return a data reference, even if you have not called RTPPBAddPacketRepeatedData .You must either pass in a nil to the data reference when adding literal or sample data, or you must release the data by calling this function.

RTPPBEndPacket

A media packetizer calls this function to tell a packet builder that a packet is complete.



 
ComponentResult RTPPBEndPacket (

                     RTPPacketBuilder rtpb,

                     SInt32 inFlags,

                     RTPPacketGroupRef inPacketGroup,

                     RTPPacketRef inPacket,

                     UInt32 inTimeOffset,

                     UInt32 inDuration);

rtpb: The component instance of the packet builder component
inFlags: A signed 32-bit integer containing any flags you are passing. There are currently no defined flags.
inPacketGroup: The packet group containing the new packet. This is normally a reference returned by RTPPBBeginPacketGroup .
inTimeOffset: The time offset at which the media sample data contained in this packet begins, in milliseconds. This offset is added to the RTP transmission time in determining when to send the packet. Unsigned 32-bit integer.
inDuration: The duration of this packet, specified in milliseconds. Unsigned 32-bit integer.

DISCUSSION

Call this function once when each packet is complete.

RTPPBEndPacketGroup

Tell a packet builder component that a packet group is complete.



 
ComponentResult RTPPBEndPacketGroup (

                     RTPPacketBuilder rtpb,

                     SInt32 inFlags,

                     RTPPacketGroupRef inPacketGroup);

rtpb: The component instance of the packet builder component
inFlags: A signed 32-bit integer containing any flags you are passing. There are currently no defined flags.
inPacketGroup: A data reference to the packet group being ended. This is normally a data reference returned by RTPPBBeginPacketGroup .

DISCUSSION

This function should be called when all the packets in a group are complete and the media packetizer is either ready to create a new packet group or to terminate the stream.